可互动的小组件和灵动岛#

Scripting 应用支持在 小组件 和 LiveActivity（灵动岛） 中添加互动的功能，使您可以通过 Button 和 Toggle 组件创建动态、交互式的 UI。这些控件可以执行 AppIntent 来触发操作，从而增强小组件和 LiveActivity 的功能。

1. AppIntent 简介#

什么是 AppIntent？#

AppIntent 定义了一个由控件（如 Button 或 Toggle）触发的特定操作，用于小组件或 LiveActivity UI。AppIntent 将 UI 组件与可执行逻辑连接起来，实现无缝交互。

支持的协议#

AppIntent 可以实现以下协议：

• AppIntent：通用意图，用于触发自定义操作。
• AudioPlaybackIntent：处理音频播放（如播放、暂停或切换音频状态）。
• AudioRecordingIntent：管理音频录制状态（需要 iOS 18+，并且在录制期间保持 LiveActivity 活跃）。
• LiveActivityIntent：修改或管理 LiveActivity 状态。

2. 注册 AppIntent#

在使用 AppIntent 之前，必须通过 AppIntentManager.register 方法在 app_intents.tsx 文件中注册。

示例：注册 AppIntent#

1// app_intents.tsx
2
3import { AppIntentManager, AppIntentProtocol } from "scripting"
4
5// 注册不带参数的 AppIntent
6const IntentWithoutParams = AppIntentManager.register({
7  name: "IntentWithoutParams",
8  protocol: AppIntentProtocol.AppIntent,
9  perform: async (params: undefined) => {
10    // 执行自定义操作
11    console.log("Intent 被触发")
12    // 可选：刷新小组件
13    Widget.reloadAll()
14  }
15})
16
17// 注册带参数的 AppIntent
18const ToggleIntentWithParams = AppIntentManager.register({
19  name: "ToggleIntentWithParams",
20  protocol: AppIntentProtocol.AudioPlaybackIntent,
21  perform: async (audioName: string) => {
22    // 根据参数执行操作
23    console.log(`切换音频播放状态：${audioName}`)
24    Widget.reloadAll()
25  }
26})

3. 在小组件或 LiveActivity UI 中使用 AppIntent#

注册完 AppIntent 后，可以在 widget.tsx 或 LiveActivity UI 文件中的 Button 和 Toggle 等交互组件中链接这些 AppIntent。

示例：在小组件中使用 AppIntent#

1// widget.tsx
2
3import { VStack, Button, Toggle } from "scripting"
4import { IntentWithoutParams, ToggleIntentWithParams } from "./app_intents"
5
6function WidgetView() {
7  const [checked, setChecked] = useState(false)
8
9  return (
10    <VStack>
11      <Button
12        title="点击我"
13        intent={IntentWithoutParams(undefined)} // 触发无参数的 AppIntent
14      />
15      <Toggle
16        title="播放或暂停"
17        value={checked}
18        intent={ToggleIntentWithParams("audio_name")} // 触发带参数的 AppIntent
19      />
20    </VStack>
21  )
22}
23
24// 展示小组件
25Widget.present(<WidgetView />)

4. API 参考#

AppIntentManager.register#

注册一个可在小组件或 LiveActivity UI 中使用的 AppIntent。

参数：#

• name (string)：意图的唯一名称。
• protocol (AppIntentProtocol)：指定意图类型（如 AppIntent、AudioPlaybackIntent）。
• perform (function)：当触发意图时执行的函数。

返回：#

• 一个 AppIntentFactory 函数，可用于创建已注册意图的实例。

Button 组件#

可点击的按钮，用于触发 AppIntent。

属性：#

• title (string)：按钮的标签。
• intent (AppIntent<any>)：按钮被点击时执行的 AppIntent。
• systemImage (可选)：按钮上显示的 SF Symbol 图标。

Toggle 组件#

切换开关，切换值时触发 AppIntent。

属性：#

• value (boolean)：切换状态（开/关）。
• intent (AppIntent<any>)：切换时执行的 AppIntent。
• title (string)：切换的标签。
• systemImage (可选)：切换上显示的 SF Symbol 图标。

5. 注意事项和最佳实践#

• 在 perform 函数中使用 Widget.reloadAll() 可在执行意图后动态更新小组件。
• 将所有 AppIntent 定义在 app_intents.tsx 文件中，方便组织和重用。
• 根据意图的功能选择合适的协议（如 AudioPlaybackIntent）。

尽情使用 Scripting 创建互动小组件和 LiveActivity 吧！ 通过 AppIntent 实现动态、交互式 UI，释放您的创造力！